Add changes/database and changes/zone endpoints; deprecate zones/changes (#401, #47, #46) by leogdion · Pull Request #429 · brightdigit/MistKit

leogdion · 2026-08-20T19:43:02Z

Summary

Implements CloudKit's two current changes/* endpoints and reconciles the change-tracking naming confusion documented in #401.

Apple endpoint	Purpose	Page primitive	Auto-paginating	Status
`records/changes`	Fetching Record Changes	`fetchRecordChanges`	`fetchAllRecordChanges`	already shipped
`changes/database`	Fetching Database Changes — which zones changed	`fetchDatabaseChanges`	`fetchAllDatabaseChanges`	new (#46)
`changes/zone`	Fetching Record Zone Changes — records within zones	`fetchRecordZoneChanges`	`fetchAllRecordZoneChanges`	new (#47)
`zones/changes`	Fetching Zone Changes	~~`fetchZoneChanges`~~	~~`fetchAllZoneChanges`~~	deprecated by Apple

Both new operations follow the existing page-primitive + auto-paginating-extension pattern, with maxPages ceilings and stuck-token detection, matching fetchAllRecordChanges.

#401 — the three requested resolutions

Spec — changes/database and changes/zone added to openapi.yaml and regenerated; zones/changes marked deprecated in favor of changes/database.
Service — wrappers added for both. fetchZoneChanges / fetchAllZoneChanges are now @available(*, deprecated), pointing at fetchDatabaseChanges. Per the repo's @available convention, deprecated is correct here because these symbols have a replacement.
Docs — the README roadmap now lists all four endpoints with both Apple's names and MistKit's method names, and reflects the deprecation. AGENTS.md (CLAUDE.md) ops table updated.

Per-zone failure handling

changes/database and changes/zone both return per-zone results that can fail individually. Rather than dropping failures, the result types expose both sides — DatabaseChangesResult.changedZones / .failures and RecordZoneChangesResult.changes / .failures, backed by ZoneChangeResult / ZoneRecordChangesResult and ZoneOperationFailure. This follows the RecordResult success-or-failure pattern the repo applies elsewhere.

Verification

Run on macOS, Apple Swift 6.3.2 (arm64-apple-macosx28.0):

Check	Result
`swift build`	Build complete
`swift test`	573 tests / 182 suites passing
`./Scripts/lint.sh`	0 violations in 416 files, no unused code (periphery ran)
`swift-format`	Clean
`./Scripts/generate-openapi.sh`	Reproduces the committed `Sources/MistKitOpenAPI/` byte-identically

Not verified locally — relying on CI: wasm32/wasm-embedded, Windows, Android, Linux, and the non-macOS Apple platforms.

Wire format

Local .claude/docs/webservices.md is abbreviated on these endpoints, so shapes were taken from Apple's archived CloudKit Web Services Reference:

No live-service call was made. Field names come from the archived reference, not from an observed payload.

Warning

Possible pre-existing bug, deliberately not changed here. Apple documents zones/changes as using metaSyncToken, but MistKit sends and reads syncToken. If the doc is right, that pagination is silently broken. It was left alone because Apple's own page contradicts itself — the moreComing text refers back to "the included syncToken key" — so this needs a live-response check rather than a doc-driven guess. Surfaced from #386 review; worth its own issue.

Note on this branch's history

The implementing agent hit a cross-worktree git stash collision mid-run (the stash stack is repo-global, so a sibling worktree's stash pop displaced this branch's WIP) and then stalled before finishing verification. The work was recovered intact and checkpointed in 79f1f31; de59ebd then resolves the 14 SwiftLint violations that were still outstanding, plus two periphery findings introduced by the file splits needed to satisfy the file-length rule. Full verification above was re-run from scratch on the final tree, not inherited.

Closes #401
Closes #47
Closes #46

🤖 Generated with Claude Code

coderabbitai · 2026-08-20T19:43:10Z

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 76cb2e88-c749-4b5b-9bb7-5f0ba1b71e13

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

🔍 Trigger review

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands.}

claude · 2026-08-20T19:49:05Z

Review

Reviewed the diff (excluding generated Sources/MistKitOpenAPI/*). This is a clean, well-structured addition that follows the repo's established patterns closely — the OperationResult<Success, Target> / OperationFailure<Target> reuse for ZoneChangeResult / ZoneRecordChangesResult is exactly the "RecordResult pattern everywhere" convention the repo has been converging on, and the per-file splits keep everything under the length lint. Test coverage for both new operations (success, error-handling, pagination, pagination-limits/stuck-token) is thorough and mirrors the existing fetchAllRecordChanges/fetchAllZoneChanges test shape.

A few things worth a look before/after merge:

1. `numberAsStrings` is added to the spec but unreachable from the curated API (minor/completeness)

openapi.yaml adds numberAsStrings to both the changes/zone request body and RecordZoneChangesRequestZone (and it generates fine into MistKitOpenAPI.Types), but neither ZoneChangesRequest (Sources/MistKit/Models/Zones/ZoneChangesRequest.swift) nor CloudKitService.fetchRecordZoneChanges ever sets it — so it's permanently nil/default and callers of the curated API have no way to opt into it. Since this field doesn't exist anywhere else in the codebase yet, there's no established precedent either way. Worth either wiring it through ZoneChangesRequest/fetchRecordZoneChanges, or dropping it from the spec until it's actually supported.

2. `zoneID` isn't `required` on the new success schemas (minor/spec-accuracy)

DatabaseChangedZone and RecordZoneChangesZoneResult both declare zoneID as optional, even though CloudKit always includes it on success and the Swift side (ZoneTarget.init(from:), ZoneInfo.init(fromZoneID:)) throws ConversionError.zoneMissingID/zoneMissingName if it's absent. Not a functional bug given the fail-loud philosophy, but marking it required: would make the spec (and generated docs) reflect reality instead of relying on a runtime throw.

3. `ZoneChangesAccumulator.finish()` drops previously-accumulated records if a zone later fails (edge case)

In Sources/MistKit/Models/Zones/ZoneChangesAccumulator.swift, if a zone succeeds on round 1 (accumulating records) but its zone entry comes back as a ZoneFetchFailure on a later round (e.g. zone deleted mid-pagination), finish() returns .failure(...) for that zone — the records gathered in earlier rounds for it are silently discarded rather than surfaced alongside the failure. Probably rare in practice, but worth a doc note (or intentionally deciding this is fine) since it's not obvious from the call site.

4. Sibling auto-paginators return different shapes (observation, not a defect)

fetchAllDatabaseChanges returns a raw tuple (zones:, syncToken:), matching the existing fetchAllZoneChanges/fetchAllRecordChanges convention. fetchAllRecordZoneChanges, added in the same PR, returns the full RecordZoneChangesResult struct instead. This looks intentional and justified (per-zone moreComing/failures don't fit a flat tuple), but it's a visible inconsistency between two APIs shipped together — might be worth a one-line note in the PR/README explaining why they differ, since a future reader may assume it's accidental.

5. Initial `zones:` list isn't deduplicated before the first request (very minor)

fetchAllRecordZoneChanges seeds pending = zones directly from the caller-supplied array for round 1, while ZoneChangesAccumulator.init dedupes by zone name for its internal bookkeeping and all subsequent rounds. If a caller accidentally passes duplicate zoneIDs, only the first request actually contains the duplicates; that's likely harmless (CloudKit will just answer twice for round 1, and the accumulator's record(changes:) last-write-wins per name), but flagging in case it's not the intended contract.

Nits

README's new "Change Tracking" example shadows a local let database = try await service.fetchDatabaseChanges(...) against the database: parameter name used everywhere else in the doc for the Database enum. Purely cosmetic, but a quick rename (e.g. databaseChanges) would avoid a double-take.

Things that look right

zonePaginationLimitExceeded/paginationLimitExceeded on the two new paginators correctly reuse the pre-existing CloudKitError cases and are well-documented as dropping in-flight failures on the maxPages ceiling (consistent with existing behavior, not new).
Stuck-token detection in both fetchAllDatabaseChanges (empty zones + unchanged token) and ZoneChangesAccumulator.merge (no records + unchanged token) is correct and tested.
zones/changes deprecation is applied consistently: @available(*, deprecated) on both fetchZoneChanges and fetchAllZoneChanges, matching the repo's stated convention for symbols with a replacement, plus doc pointers to the new methods.
No security concerns — this is purely additional read/pagination surface over existing auth plumbing; no new credential handling, logging, or external I/O paths.

Nice work — this closes out #401/#47/#46 cleanly and the history note about the cross-worktree stash recovery is a good example of the "never git stash in this multi-worktree repo" lesson being captured back into .claude/memory/.

codecov · 2026-08-20T19:50:19Z

Codecov Report

❌ Patch coverage is 93.83754% with 22 lines in your changes missing coverage. Please review.
⚠️ Please upload report for BASE (v1.0.0-beta.4@d70e6ef). Learn more about missing BASE report.

Files with missing lines	Patch %	Lines
...itService/CloudKitError+ZoneErrorDescription.swift	0.00%	10 Missing ⚠️
...udKitService/CloudKitService+DatabaseChanges.swift	94.73%	3 Missing ⚠️
...oudKitService/CloudKitError+ErrorDescription.swift	33.33%	2 Missing ⚠️
Sources/MistKit/Models/ZoneTarget.swift	88.88%	2 Missing ⚠️
.../MistKit/Models/Zones/ZoneChangesAccumulator.swift	97.18%	2 Missing ⚠️
.../CloudKitService+RecordZoneChangesPagination.swift	96.87%	1 Missing ⚠️
...tions/Operations.fetchDatabaseChanges.Output.swift	93.75%	1 Missing ⚠️
...ons/Operations.fetchRecordZoneChanges.Output.swift	93.75%	1 Missing ⚠️

Additional details and impacted files

@@               Coverage Diff                @@
##             v1.0.0-beta.4     #429   +/-   ##
================================================
  Coverage                 ?   81.45%           
================================================
  Files                    ?      191           
  Lines                    ?     4719           
  Branches                 ?        0           
================================================
  Hits                     ?     3844           
  Misses                   ?      875           
  Partials                 ?        0

Flag	Coverage Δ
mistdemo-spm-macos	`11.31% <9.80%> (?)`
mistdemo-swift-6.2-jammy	`11.31% <9.80%> (?)`
mistdemo-swift-6.2-noble	`11.31% <9.80%> (?)`
mistdemo-swift-6.3-jammy	`11.31% <9.80%> (?)`
mistdemo-swift-6.3-noble	`11.31% <9.80%> (?)`
mistdemo-swift-6.4-jammy	`11.31% <9.80%> (?)`
mistdemo-swift-6.4-noble	`11.31% <9.80%> (?)`
spm	`80.01% <93.83%> (?)`
swift-6.1-jammy	`80.37% <93.83%> (?)`
swift-6.1-noble	`80.20% <93.83%> (?)`
swift-6.2-jammy	`80.13% <93.83%> (?)`
swift-6.2-noble	`80.24% <93.83%> (?)`
swift-6.3-jammy	`79.99% <93.83%> (?)`
swift-6.3-noble	`80.01% <93.83%> (?)`
swift-6.4-jammy	`80.13% <93.83%> (?)`
swift-6.4-noble	`80.13% <93.83%> (?)`

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

leogdion · 2026-08-25T18:32:33Z

Review/merge order note

Proposed order for the v1.0.0-beta.4 queue: #425 → #424 → #427 → #426 → #429 → #428

This PR should go fifth — after #424 and #427. It's large and additive (openapi.yaml +291, Types.swift +1643), and it overlaps both of them:

Sources/MistKit/CloudKitService/CloudKitError.swift — Remove deprecated API, model server error codes, refactor FieldValue conversion, add cloud toolchain #424 rewrites it (+52/−14), this adds +5. Rebase onto the new error model rather than the old one.
Sources/MistKit/CloudKitService/CloudKitService+ZoneOperations.swift — Add confirmed zone metadata (syncToken, atomic) to zone schemas #427 touches it (+2/−2), this reworks it (+13/−15).
Sources/MistKitOpenAPI/Types.swift — Add confirmed zone metadata (syncToken, atomic) to zone schemas #427 restructures the zone schemas onto a shared Zone type. Regenerate with Scripts/OpenAPITools/ (landing in Remove deprecated API, model server error codes, refactor FieldValue conversion, add cloud toolchain #424) once Add confirmed zone metadata (syncToken, atomic) to zone schemas #427 is in; do not hand-merge the generated file.

⚠️ Decide the deprecation policy before merging

This PR adds two new @available(*, deprecated) declarations — fetchZoneChanges / fetchAllZoneChanges, pointing at fetchDatabaseChanges. #424's summary states: "No @available(*, deprecated) declarations remain in Sources/MistKit."

Both can't hold at 1.0. Two ways out:

(a) Remove, don't deprecate. Pre-1.0 there are no compatibility obligations, so fetchZoneChanges/fetchAllZoneChanges are deleted outright and zones/changes simply doesn't ship a wrapper. Keeps Remove deprecated API, model server error codes, refactor FieldValue conversion, add cloud toolchain #424's invariant clean.
(b) Narrow Remove deprecated API, model server error codes, refactor FieldValue conversion, add cloud toolchain #424's claim to "no deprecations carried over from before beta.4," which leaves room for this PR's deprecation as written — defensible, since Apple deprecating the endpoint is genuinely new information rather than legacy debt.

I'd lean (a) for a 1.0, but it's a judgment call — the point is to settle it deliberately rather than let merge order decide it.

Testing

changes/database and changes/zone are absent from .claude/docs/webservices.md, so the wire format here rests on the archived reference. This needs a live CloudKit integration run, not just the unit suite — specifically:

the per-zone failure split (DatabaseChangesResult.changedZones / .failures) against a database where at least one zone genuinely errors, so the failure branch isn't only exercised by mocks;
moreComing / sync-token pagination across a real multi-page response, including the stuck-token detection;
the maxPages ceiling actually tripping.

Resolves the 14 SwiftLint violations outstanding when the implementing agent stalled, plus two periphery findings introduced by the file splits: - Expand `guard ... else { return nil }` one-liners (conditional_returns_on_newline) in DatabaseChangesResult, RecordZoneChangesResult, ZoneChangesAccumulator and CloudKitService+DatabaseChanges. - Put each argument on its own line in the paginator's accumulator.merge(...) call (multiline_arguments{,_brackets}). - Wrap the unbreakable DocC symbol link in ZoneChangesRequest with a scoped line_length disable/enable pair, keeping the doc comment contiguous so it stays attached to the declaration. - Split CloudKitError+ZoneErrorDescription.swift out of CloudKitError+ErrorDescription.swift, and ...FetchRecordZoneChanges+PaginationLimits.swift out of ...+Pagination.swift, to bring both files under the length limit. - Drop the import and test helper the splits left unused. swift test: 573 tests / 182 suites passing. Scripts/lint.sh: 0 violations in 416 files, no unused code. generate-openapi.sh reproduces the committed Sources/MistKitOpenAPI output. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Introduce fetch-database-changes and fetch-zone-record-changes CLI, migrate phases/web off deprecated fetchZoneChanges, and keep fetch-changes on records/changes. Co-authored-by: Cursor <cursoragent@cursor.com>

ci skip Co-authored-by: Cursor <cursoragent@cursor.com>

…in lint. Exercise database/zone change APIs against a provisioned custom zone with fatal assertions and incremental sync-token checks, and opt periphery out of lint until the index-store path mismatch is resolved. Co-authored-by: Cursor <cursoragent@cursor.com>

Add changes/database and changes/zone panels with a two-step prefill flow, and disable the FetchDatabaseChanges/FetchRecordZoneChanges test suites on wasm to avoid CI OOM. Co-authored-by: Cursor <cursoragent@cursor.com>

`modifyZones` mapped every entry straight through as a success, so a batch where some zones failed was reported as a partial success naming no zone and discarding CloudKit's `serverErrorCode`/`reason`. It now returns a bare `[ZoneChangeResult]` — one entry per zone the server returned — mirroring how `modifyRecords` returns a bare `[RecordResult]`. `zones/modify` carries no batch-level metadata, so there is deliberately no `DatabaseChangesResult`-style wrapper struct. `ZoneChangeResult` / `ZoneOperationFailure` from #429 are reused rather than duplicated; the only new code is a second `init(from:)` overload keyed off the generated `ZonesModifyResponse.zonesPayloadPayload`. Two convenience-wrapper bugs fall out of this: - `createZone` threw a bare `.invalidResponse` with no code, reason or zone name when CloudKit rejected the create. It now calls `.get()`, throwing `.zoneOperationFailed` with the full failure. - `deleteZone` discarded the result entirely, so a `ZONE_NOT_FOUND` delete was reported to the caller as success. It now checks every entry. `.zones` / `.failures` accessors are added as concrete `Array` extensions (`[ZoneChangeResult]`, plus `.records`/`.failures` on `[RecordResult]`) rather than one generic extension over `OperationResult<Success, Target>`: Swift cannot bind free generic parameters in an extension's `where` clause. BREAKING: `modifyZones` returns `[ZoneChangeResult]`, not `[ZoneInfo]`. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Xs1c8vvxjCxqZiStcmuPS2

PR #429 gated periphery behind an opt-in RUN_PERIPHERY=1 because periphery could no longer find SwiftPM's index store. Fix the cause instead of skipping the check. The store's location depends on the build system: swiftbuild (the SwiftPM default since Swift 6.2) writes `.build/out`, the native build system writes `.build/<triple>/debug/index/store`, and older toolchains wrote `.build/debug/index/store`. lint.sh now probes those three candidates for a `v5/units` directory and passes the winner to periphery's `--index-store-path` (3.7.4, pinned in mise.toml), with `--skip-build` stated explicitly to silence periphery's implied-flag warning. The build step above already produced the store, so skipping periphery's own build is both correct and faster. The RUN_PERIPHERY opt-in and the stale explanatory comment are gone; periphery runs by default in local runs again. The $CI and CLAUDE_CODE_REMOTE exclusions are unchanged, so CI behavior is identical. Examples/MistDemo/Scripts/lint.sh gets the same resolution; it is an in-repo package, not a subrepo. Its BushelCloud and CelestraCloud siblings are git subrepos and are left alone. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Xs1c8vvxjCxqZiStcmuPS2

* Remove docs/transcriptions/ (1.27 MB of talk exports) Deletes the five conference-talk transcription exports (paragraphs.json, timestamps.json, transcript.srt/.txt/.vtt, 1,272,627 bytes total). They are build-irrelevant artifacts of the 2026-05 "CloudKit as Your Backend" dry run and are not referenced by docs/README.md. All five blobs are preserved on the pushed annotated tag archive/talk-prep-2026-05-17, so they remain recoverable even though main is squash-merged. docs/talk-feedback.md still cites the raw transcript in its cleanup and brand/spelling sections, so the reference is kept and repointed at the archive tag on GitHub rather than dropped. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Xs1c8vvxjCxqZiStcmuPS2 * Delete .claude/docs/MILESTONE-19-HANDOFF.md Time-boxed WIP handoff (7,606 B) from the Claude Code web session behind PR #424: it points at branch `claude/parallel-agents-work-trees-pbumvn` and head `fb84e52`, both long superseded. `git grep MILESTONE-19` finds no reference to it anywhere outside the file itself, and it is the only file in .claude/docs/ that is a session snapshot rather than reference material. Still recoverable from PR #424's own commits on GitHub (added by 1411227; blob a75fbcd). Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Xs1c8vvxjCxqZiStcmuPS2 * Re-enable periphery in lint.sh via explicit --index-store-path PR #429 gated periphery behind an opt-in RUN_PERIPHERY=1 because periphery could no longer find SwiftPM's index store. Fix the cause instead of skipping the check. The store's location depends on the build system: swiftbuild (the SwiftPM default since Swift 6.2) writes `.build/out`, the native build system writes `.build/<triple>/debug/index/store`, and older toolchains wrote `.build/debug/index/store`. lint.sh now probes those three candidates for a `v5/units` directory and passes the winner to periphery's `--index-store-path` (3.7.4, pinned in mise.toml), with `--skip-build` stated explicitly to silence periphery's implied-flag warning. The build step above already produced the store, so skipping periphery's own build is both correct and faster. The RUN_PERIPHERY opt-in and the stale explanatory comment are gone; periphery runs by default in local runs again. The $CI and CLAUDE_CODE_REMOTE exclusions are unchanged, so CI behavior is identical. Examples/MistDemo/Scripts/lint.sh gets the same resolution; it is an in-repo package, not a subrepo. Its BushelCloud and CelestraCloud siblings are git subrepos and are left alone. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Xs1c8vvxjCxqZiStcmuPS2 --------- Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>

`modifyZones` mapped every entry straight through as a success, so a batch where some zones failed was reported as a partial success naming no zone and discarding CloudKit's `serverErrorCode`/`reason`. It now returns a bare `[ZoneChangeResult]` — one entry per zone the server returned — mirroring how `modifyRecords` returns a bare `[RecordResult]`. `zones/modify` carries no batch-level metadata, so there is deliberately no `DatabaseChangesResult`-style wrapper struct. `ZoneChangeResult` / `ZoneOperationFailure` from #429 are reused rather than duplicated; the only new code is a second `init(from:)` overload keyed off the generated `ZonesModifyResponse.zonesPayloadPayload`. Two convenience-wrapper bugs fall out of this: - `createZone` threw a bare `.invalidResponse` with no code, reason or zone name when CloudKit rejected the create. It now calls `.get()`, throwing `.zoneOperationFailed` with the full failure. - `deleteZone` discarded the result entirely, so a `ZONE_NOT_FOUND` delete was reported to the caller as success. It now checks every entry. `.zones` / `.failures` accessors are added as concrete `Array` extensions (`[ZoneChangeResult]`, plus `.records`/`.failures` on `[RecordResult]`) rather than one generic extension over `OperationResult<Success, Target>`: Swift cannot bind free generic parameters in an extension's `where` clause. BREAKING: `modifyZones` returns `[ZoneChangeResult]`, not `[ZoneInfo]`. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Xs1c8vvxjCxqZiStcmuPS2

) (#443) * Model per-zone failures on zones/modify; clarify zones/changes syncToken `ZonesModifyResponse.zones` items become `oneOf: [ZoneFetchFailure, Zone]`, matching `changes/database` and `changes/zone`. `zones/modify` is a batch endpoint whose realistic failure mode is partial, and Apple routes all four zone endpoints' failures through the same Zone Fetch Error Dictionary, so the error variant already exists — it just was not wired to this response. The failure variant is listed first, matching every other `oneOf` in the spec. `ZoneFetchFailure` requires `serverErrorCode`, so a success payload fails that branch and falls through to `Zone`. Also rewords the `zones/changes` request `syncToken` description (#433 part 3): it was described as "Meta-sync token", a name the spec does not use for the key. The key stays `syncToken` (#430); only the prose is corrected. Regenerating also repairs Sources/MistKitOpenAPI reproducibility: CodeFactor's bot alphabetized the Foundation imports in Client.swift/Types.swift in 61235b5, so `./Scripts/generate-openapi.sh` no longer reproduced the committed output. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Xs1c8vvxjCxqZiStcmuPS2 * modifyZones returns [ZoneChangeResult] and surfaces per-zone failures `modifyZones` mapped every entry straight through as a success, so a batch where some zones failed was reported as a partial success naming no zone and discarding CloudKit's `serverErrorCode`/`reason`. It now returns a bare `[ZoneChangeResult]` — one entry per zone the server returned — mirroring how `modifyRecords` returns a bare `[RecordResult]`. `zones/modify` carries no batch-level metadata, so there is deliberately no `DatabaseChangesResult`-style wrapper struct. `ZoneChangeResult` / `ZoneOperationFailure` from #429 are reused rather than duplicated; the only new code is a second `init(from:)` overload keyed off the generated `ZonesModifyResponse.zonesPayloadPayload`. Two convenience-wrapper bugs fall out of this: - `createZone` threw a bare `.invalidResponse` with no code, reason or zone name when CloudKit rejected the create. It now calls `.get()`, throwing `.zoneOperationFailed` with the full failure. - `deleteZone` discarded the result entirely, so a `ZONE_NOT_FOUND` delete was reported to the caller as success. It now checks every entry. `.zones` / `.failures` accessors are added as concrete `Array` extensions (`[ZoneChangeResult]`, plus `.records`/`.failures` on `[RecordResult]`) rather than one generic extension over `OperationResult<Success, Target>`: Swift cannot bind free generic parameters in an extension's `where` clause. BREAKING: `modifyZones` returns `[ZoneChangeResult]`, not `[ZoneInfo]`. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Xs1c8vvxjCxqZiStcmuPS2 * Test per-zone modifyZones failures and the create/delete wrappers Adds a raw-dictionary `ResponseConfig.modifyZonesResponse(zones:)` builder — so a single response can mix success entries and zone error entries — mirroring `databaseChangesResponse(zones:syncToken:moreComing:)`, and a `makeService(zones:)` harness over it. New tests: a mixed batch keeps the successes and reports the failure with its zone name/code/reason; `.get()` on a failed entry throws `.zoneOperationFailed`; zone metadata survives the new success variant; `createZone` surfaces the `ZoneOperationFailure` instead of `.invalidResponse`; and `deleteZone` throws on `ZONE_NOT_FOUND` rather than reporting success. Verified the failure tests fail when the service is reverted to dropping error entries. `ZoneMetadataTests` now matches on the `oneOf` success variant. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Xs1c8vvxjCxqZiStcmuPS2 * MistDemo: adopt the [ZoneChangeResult] return from modifyZones - `modify-zones` announces per-zone rejections on stderr (matching how `modify` reports per-record failures) and keeps stdout to the zones that were actually modified, so the JSON/CSV/table output stays machine-parseable. `outputResults` requires `Encodable` and `OperationResult` is `Sendable`-only, so the results cannot be rendered directly. - `webModifyZones` collapses the results all-or-nothing via `.get()`, matching the documented decision in `webLookupRecords`, so the web panel shows a rejection instead of silently returning fewer zones than were asked for. Its `[ZoneInfo]` signature is unchanged, so `WebBackend`, the routes and the mock backend need no changes. - `ModifyZonesPhase` asserted nothing about the results; it now fails the integration run when a create or the cleanup delete is rejected. Split into `createAndVerify` to stay under the cyclomatic-complexity limit. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Xs1c8vvxjCxqZiStcmuPS2 * Add CI guard for generated OpenAPI output; document modifyZones results CodeFactor's bot committed to `Sources/MistKitOpenAPI/` in 61235b5, reordering imports in generated files, which broke `./Scripts/generate-openapi.sh` reproducibility until this branch regenerated them. Nothing checked that. `check-generated-openapi.yml` now regenerates and runs `git diff --exit-code Sources/MistKitOpenAPI/` on every PR. It builds the generator from `Scripts/OpenAPITools`, whose version is pinned in sync with mise.toml, so the check is self-contained. That fallback build leaves SwiftPM checkouts in `Scripts/OpenAPITools/.build`, which SwiftLint then walked (the bare `.build` exclude only matches the repo root one) — added as an explicit exclude. Docs: AGENTS.md's per-zone-failures paragraph now covers `zones/modify` and records the oneOf ordering rationale, the operations table names the new return type, and README points at `modifyZones` alongside `createZone`/`deleteZone`. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Xs1c8vvxjCxqZiStcmuPS2 * Rename the zones/changes wire token to metaSyncToken (#430) A live container run (iCloud.com.brightdigit.MistDemo / development / private, web-auth) proved `zones/changes` neither returns nor honors `syncToken`: - The response's top-level keys are exactly `[moreComing, metaSyncToken, zones]` — no `syncToken` at all. - Round-tripping the same baseline token: sending `{"syncToken": …}` (what MistKit sent) returned all 40 zones again — the key is silently ignored and page one replays. Sending `{"metaSyncToken": …}` returned 0 zones — honored and correctly advanced. So `fetchZoneChanges` / `fetchAllZoneChanges` pagination has never worked. This supersedes the description-only wording fix in the previous commit, which assumed the mismatch was documentation rather than behavior. Renames the wire key for `zones/changes` **only** — the request body property and `ZoneChangesResponse` — and regenerates. `changes/database`, `changes/zone` and `records/changes` legitimately use `syncToken` and are untouched. Every Swift-facing name is deliberately unchanged: `ZoneChangesResult.syncToken` and its `init(syncToken:)` label, and the `fetchZoneChanges(syncToken:)` / `fetchAllZoneChanges(syncToken:)` argument labels. `MistKitOpenAPI` is an `internal import`, so a wire-key rename is not source-breaking for consumers; only the mapping in `ZoneChangesResult.init(from:)` and the request construction in `CloudKitService+ZoneOperations.swift` change. Adds `CloudKitServiceTests.FetchZoneChanges+WireFormat.swift`, which pins that MistKit sends `metaSyncToken` and never `syncToken`, reads `metaSyncToken` in preference to a decoy `syncToken`, and feeds the previous page's token back under the honored key. Existing `zones/changes` fixtures were emitting the wrong key and are updated. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Xs1c8vvxjCxqZiStcmuPS2 * Add tests for [RecordResult].records and .failures accessors Covers the retro-fit Array+RecordResult helpers so codecov patch coverage meets the project threshold on #443. Co-authored-by: Cursor <cursoragent@cursor.com> --------- Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com> Co-authored-by: Cursor <cursoragent@cursor.com>

leogdion force-pushed the 47-401-change-tracking-endpoints branch 2 times, most recently from 3546bcf to 99b9f1e Compare August 21, 2026 19:14

This was referenced Aug 25, 2026

Add custom/shared zone support to the query path (#146) #426

Merged

Add records/resolve and records/accept share operations (#41, #42) #428

Merged

leogdion and others added 4 commits August 28, 2026 06:47

WIP: recovered change-tracking work (pre-verification checkpoint)

73fce9f

Add MistDemo coverage for database and zone change tracking

cc4bd70

Introduce fetch-database-changes and fetch-zone-record-changes CLI, migrate phases/web off deprecated fetchZoneChanges, and keep fetch-changes on records/changes. Co-authored-by: Cursor <cursoragent@cursor.com>

Classify zoneOperationFailed in serverErrorDetail switch after rebase.

513cb4e

ci skip Co-authored-by: Cursor <cursoragent@cursor.com>

leogdion force-pushed the 47-401-change-tracking-endpoints branch from 99b9f1e to 513cb4e Compare August 28, 2026 10:49

leogdion and others added 2 commits August 28, 2026 07:30

leogdion merged commit 535eb2f into v1.0.0-beta.4 Aug 28, 2026
84 checks passed

leogdion deleted the 47-401-change-tracking-endpoints branch August 28, 2026 15:53

Navigation Menu

Uh oh!

Add changes/database and changes/zone endpoints; deprecate zones/changes (#401, #47, #46) - #429

Add changes/database and changes/zone endpoints; deprecate zones/changes (#401, #47, #46)#429
leogdion merged 6 commits into
v1.0.0-beta.4from
47-401-change-tracking-endpoints

leogdion commented Aug 20, 2026

Uh oh!

coderabbitai Bot commented Aug 20, 2026 •

edited

Loading

Review skipped

Uh oh!

claude Bot commented Aug 20, 2026

Uh oh!

codecov Bot commented Aug 20, 2026 •

edited

Loading

Uh oh!

leogdion commented Aug 25, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Uh oh!

Conversation

leogdion commented Aug 20, 2026

Summary

#401 — the three requested resolutions

Per-zone failure handling

Verification

Wire format

Note on this branch's history

Uh oh!

coderabbitai Bot commented Aug 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Review skipped

Uh oh!

claude Bot commented Aug 20, 2026

Review

1. numberAsStrings is added to the spec but unreachable from the curated API (minor/completeness)

2. zoneID isn't required on the new success schemas (minor/spec-accuracy)

3. ZoneChangesAccumulator.finish() drops previously-accumulated records if a zone later fails (edge case)

4. Sibling auto-paginators return different shapes (observation, not a defect)

5. Initial zones: list isn't deduplicated before the first request (very minor)

Nits

Things that look right

Uh oh!

codecov Bot commented Aug 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

leogdion commented Aug 25, 2026

Review/merge order note

⚠️ Decide the deprecation policy before merging

Testing

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

coderabbitai Bot commented Aug 20, 2026 •

edited

Loading

1. `numberAsStrings` is added to the spec but unreachable from the curated API (minor/completeness)

2. `zoneID` isn't `required` on the new success schemas (minor/spec-accuracy)

3. `ZoneChangesAccumulator.finish()` drops previously-accumulated records if a zone later fails (edge case)

5. Initial `zones:` list isn't deduplicated before the first request (very minor)

codecov Bot commented Aug 20, 2026 •

edited

Loading